PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / sdimage.com / SDIMAGE.DOC < prev next >

Wrap

Text File | 1989-02-14 | 20.9 KB | 528 lines

SDIMAGE V1.03 by Michael Day as of 14 February 1989 SDImage is a Turbo Pascal unit designed to allow saving any BGI screen to disk. SDImage uses GetImage and PutImage to do the save. The Program works by using an intermediate buffer to save the image. The size of the buffer is user definable. Image Buffer: There are 20 image buffers available for use. At startup, the buffers are not allocated on the heap, only the buffer headers exist. This keeps memory usage at a minimum since the buffers are only allocated when they are needed. You can also release a buffer at any time to pick up the heap space it uses. You can either predefine a buffer to the size you want, or the Image buffer will be automatically allocated when the buffer is used. Although 20 buffers should be more than enough for most applications, you can specify more (or fewer) buffers by changing the constant "MaxImageBuf" to the desired value. Buffers are used by direct reference in the command. This makes buffer usage unambiguous. When a buffer is referenced in the SaveImage command, it is first checked to see if there is an image already stored in it. If there is an image in the buffer, it is immediately flushed to disk. If the buffer does not have an image in it, then it is checked to see if the buffer has not been allocated yet. If the buffer has not been allocated, then a buffer of default size is allocated. Currently the default buffer size is 5000, but this can be redefined by changing the constant "MaxRawImage" to the desired default buffer size. Alternately, the individual buffer sizes can be changed at run time by using the "AllocImageBuf" function. Once a buffer has been assured to be clean and defined, it is tested to see if the image can completely fit in the buffer. If the image can fit in the buffer, then it is placed in the buffer and no further action taken. If the image cannot be completely placed in the buffer, then a disk save is performed. The image is moved into the buffer in pieces and flushed to disk until then entire image has been saved to disk. The buffer is left empty after a disk save. Disk Files: When an image cannot fit in a buffer it will be automatically saved to disk instead. Alternately, the image can be forced to always be directed to the disk (see the section on buffer control). Images are referenced by an image reference number (or handle). You define the image reference number to be used with SaveImage or DisplayImage. This number is used to keep track of the image. If you use the same number for an image, then it will normally be overwritten. An exception to this is if the image is in a different buffer. There are no checks made to see if an image is in another buffer. When an image is written to disk, a file is created using a name built from the image reference number. An image file uses the first three letters "SDI" followed by a leading zero filled number which is the reference number that was passed, followed by the file extension of ".IMG". An image file will remain on disk until it is either explictly erased, or the DisplayImage function is called with ImgClr = true which will cause the image to be automatically erased after the image has been displayed. Because an image will remain on disk unless explictly erased, it can be very easy to clutter up the disk with old image files. For this reason it is recommended that you place the image files in their own subdirectory. the "SetImagePath" function has been provided for this purpose. An advantage of having images on disk referenced by the image reference number is that images can be created in one program and displayed in another. A disadvantage is that the image is saved using the BGI GetImage and PutImage functions which means that the display must be the same as the display used to create the image. Saving images to disk allows for a much smaller memory requirement within a program to save images. This can be a real boon when a program grows too large and you are forced to find ways to reduce the amount of memory usage. The disadvantage is that it is much slower to save an image to disk because you have to deal with the physical access time of the disk drive. This can cause some problems in the sluggishness of the display while saving or displaying images to/from disk. To help relieve this, SDImage uses special effects to make the display look more active and thus giving the user a feeling that the computer is actually doing something to the display while it is busy working with the disk. Special Effects: Displaying images from disk can take a while to perform, so to help liven things up some special effects options are provided. The special effects work in conjunction with disk accesses. When an image is being read from disk, it usually must do multiple buffer writes. By controlling where those writes occur on the screen, special effects can be incorporated into the image display. To do this requires that the image be saved originally in the desired format. Since the special effects are tied directly to the disk/buffer transfer, special effects are not operational when an image stays in the buffer, or when there is only one buffer image in the disk file. Multiple image segments must be used to have the proper special effects. Since only large images really benifit from special effects this usually is no problem. Remember, the smaller the buffer, the smoother the special effect, but at the same time the effect will become slower as well. This can be compensated for by using a ram-disk instead of a hard disk to store the images. The Special effects are controlled by the "Style" option word that is passed to the SaveImage function. The DisplayImage function cannot control special effects. The image must be stored with the desired effect for it to be active. The lower four Style bits control the special effects operation. Bit 2 controls whether the image will be displayed as a "Pull" or via an Expand/Merge operation. Bit 1 controls whether the image will grow in the Horizontal or vertical direction. Bit 0 controls the edge that the image will grow from, or whether it will expand or merge. Bit 3 is currently unused. Style +---+-----+---------+------+-------------+ |bit| 3 | 2 | 1 | 0 | +---+-----+---------+------+-------------+ | 1 | --- | Xpd/Mrg | Horz | Xpd/Left/Dn | +---+-----+---------+------+-------------+ | 0 | --- | Pull | Vert | Mrg/Rght/Up | +---+-----+---------+------+-------------+ 0=Pull Down 1=Pull Up 2=Pull Right 3=Pull Left 4=Merge Vertical 5=Expand Vertical 6=Merge Horizontal 7=Expand Horizontal Note: Special effects only operate when the image is read from the disk, in fact it works because it uses the disk buffering as an inherent part of the effects control. Buffer Control: The upper four bits of the Style byte control the buffer operation. Bit 7 controls the Disk, and bit 6 controls the EMS. --> EMS is not currently supported in SDImage. <-- If bit 7 is on, then the image will always be saved to disk. If bit 7 is off, then the image will try to stay in the buffer if possible. Bit 6 is intended for EMS control. The intent is that if Bit 6 is on, then the image will be directed to the EMS instead of disk. If bit 6 is off, then the Disk will be used. In either case, bit 7 controls buffering activity. If bit 4 is on, then the image will be compressed using Run Length Encoding before being saved to disk. Style +---+------+-------+-----+-----+ |bit| 7 | 6 | 5 | 4 | +---+------+-------+-----+-----+ | 1 | Disk | EMS | --- | RLE | +---+------+-------+-----+-----+ | 0 | Auto | NoEMS | --- | BIN | +---+------+-------+-----+-----+ The image flow is controlled as follows: $00 -> Buffer -> Disk $40 -> Buffer -> EMS -> Disk $80 -> Disk $C0 -> EMS -> Disk Another mechanism that can be used is to refer to a ram disk for the images instead of a hard disk. This allows the special effects associated with disk operation to be used as well as the reduced program memory requirements while still keeping as fast a file access as possible. And since a ram disk can be installed in EMS memory, this would be one way to get around the current lack of EMS support in SDImage. Run Length Encoding: A modified inplace RLE encoding scheme is used to compress the image in the buffer when the Style RLE bit is set. Compressing the image saves disk space by reducing the size of the data to be stored. The amount of compression varies. Simple single color images with pull up or pull down will achieve the greatest amount of compression. Complex multi-colored images with horizontal special effects will be the least compressed. Compression will typically vary from 10% to 50% depending on the image. Using compression will slightly slow down the ImageSave because the image must be processed through the compression routine first. In the provided SDITEST program this results in a ImageSave slow down of about one second for a complete cycle (eight images). This can vary though, and in the case of simple pictures there may be an overall speedup of the save time since not as much disk write time is required. In most cases the compression will actually speed up the DisplayImage because not as much data has to be read from the disk (a significant portion of the delay when displaying). In the SDITEST program provided this speedup is about one second for a complete cycle (eight images). For simple images the speedup of reading compressed images can be significant. Buffer Notes: Although you can define just about any size buffer you wish, there are some limitations. The maximum buffers size is limited to 65521, and the minimum buffer size is limited to one row of the saved image, or the buffer size of a saved image being read. If you change the size of a buffer while an image is in the buffer, the buffer will be flushed and the image will be lost. If a buffer does not exist or is too small for the operation it will be automatically resized to an acceptable value. If an image will not fit in the buffer, then it will be placed on the disk. If the image is placed on the disk, then the buffer will be left empty at the end of the operation. Disk Notes: When an image is saved to disk a filename is created based on the image reference number. The filename consists of the three letters "SDI", followed by a left zero filled five digit number which is the image reference number used, followed by an filename extension of ".IMG". Normally an image will not be placed on the disk unless it cannot fit in the image buffer. Sometimes it is desirable to create a disk image for later recall in another program or in the same program at a later time. A disk save can be forced by setting bit 4 ($10) of the "Style" option in the SaveImage function. Disk images use one file per image. Because of this there can be a lot of image files hanging around if there are a lot of images saved. Because of this it is recommended that the images be placed in their own subdirectory. This will have the added advantage of speeding things up a bit since the directory search won't have all the other program files to deal with. Disk images will be left on the disk if the "ImgClr" option in the "DisplayImage" function is false. If ImgClr is provided as true, then the image will be erased from the disk after it has been displayed. If an image file exists on the disk by the same reference number then it will be overwritten by the new image when it is saved. You should be aware that if you don't delete the image file while the program is running it will still be on the disk after the program has been run. This was done purposely so that image files could be created to be read by other programs or at a later date with the same program. This can however cause a clutter of IMG files if you don't pay attention to this. You can remove a image file by just erasing the file. Alternately you can use the DeleteImage function to delete a specific image. If an image file is requested and not found, the DisplayImage function is aborted and returns a false condition. If a image file cannot be created, then the SaveImage function will be aborted and returns a false condition. RLE Notes: The RLE compression scheme used is a modified inplace Run Length Compression. This means that the compression takes place inside the existing data buffer. This has a significant advantage since additional buffer space is not required to perform the compression. The modified RLE compression requires that two additional words of data be attached to the beginning of each image record saved. The two words contain the physical length of the compressed record, and the offset into the record where compression actually begins. The modified RLE does not compress the entire image. Rather it only compresses that part of the image which can be compressed. This is done by first searching the image to see where compression can begin. The offset is then stored into the variable PakStart. A second routine then performs the actual compression starting at the location found. This can speed up the actual compression/decompression time since only the compressible portion of the image will be compressed/decompressed. The resulting compressed image size is saved in PakSize. The compression mechanism used is to scan though the image looking for where the actual compression can begin. The compression offset is then saved. The actual compression of the image is then performed starting at the offset found. The image is compressed by looking at the count of bytes that are the same. If the count is three or less, then no compression is done, and the data is left unchanged. If there are three or more bytes that are the same, then one copy of the byte is stored, followed by the count of same bytes that were found (max=255), followed by a zero byte to mark that it is a compression packet. Because a zero byte is used to mark compression packets, the zero value is always compressed. Which of course means that for one or two zero byte values an expansion actually occurs sine a compression packet always uses three bytes. One additional exception is the last value(s) in the image is always compressed. This is done to make the software slightly easier to write. It eliminates a potential problem that can occur if the last values in the image are not enough to compress (less than four), but more than one. To uncompress the image, it is read into a full sized buffer (equal to or greater than the length of the uncompressed image). the image is then uncompressed starting at the end of the compressed image. Decompression stops when the original compression offset is reached. As a side effect of performing the docompression inplace, the decompression routine must maintain a three byte look ahead buffer (in the cpu registers) to prevent overwriting the compression data it is reading. Sometimes the image cannot be compressed. An incompressible image will result in the compression offset pointer being equal to the length of the uncompressed image. When that situation detected, the image will not be compressed or decompressed. The header must still be saved though, so in a worst case, the image record will be 4 bytes longer than an image record saved without compression. The compression/decompression is performed in assembler so that the speed will be as fast as possible. The three routines used are implemented as INLINE macros. "ScanImg" scans the image buffer and returns the offset where compression can begin. "PakImag" compresses the image and returns the new compressed image length. "UnPakImage" decompresses the image. UnPackImage is an INLINE procedure, so there is no return value. An example compressed image is shown below: - uncompressed - - compressed - 0,0,1,0,1,1,1,1,1,1, 0,0,1,0,1,1,1,1,1,1, 2,3,4,4,5,6,6,6,7,0, 2,3,4,4,5,6,6,6,7,0, 1,1,1,1,2,3,0,0,4,5, 1,1,1,1,2,3,0,0,4,5, 6,0,0,0,1,0,0,1,0,1, 6,0,0,0,1,0,0,1,0,1, 1,1,1,1,1,1,1,1,1,1, 1,10,0, 2,2,2,2,2,2,2,2,2,2, 2,10,0, 0,0,1,0,1,1,1,1,1,1, 0,2,0, 1, 0,1,0, 1,6,0 2,2,2,2,2,2,1,2,0,3 2,6,0, 1, 2, 0,1,0, 3,1,0 RawSize = 80 PakStart = 40 PakSize = 67 SDImage Functions: AllocImageBuf(Buf:word; Size:word):boolean Allocates a specified amount of heap memory to the buffer. The buffer is automatically allocated to the default size if you don't allocate the buffer before use. You can reallocate the buffer size at anytime. If the buffer number is invalid, or there is not enough heap space to allocated the specified buffer the function will return false. ReleaseImageBuf(Buf:word):boolean Releases the heap space used by the buffer. You can release the buffer space at anytime. If the buffer is deallocated the next time you try to use it, then it will be automatically reallocated to the default size. If the buffer number given is invalid the function will return false. SetImagePath(Path:string):boolean You can specify that the images be placed in a separate subdirectory by using this function. It is recommended that you place images in a separate directory if you are saving more than a couple of images to keep directory clutter to a minimum. If the Path could not be found, then the subdirectory will be made. If the subdirectory could not be made, then the function will return false. You can preceed the path with a drive letter to direct the image to another drive. When specifying a new path, do not use the trailing '\' SDImage will handle that. Example: 'D:\SDI'. You can use the default drive by dropping the drive letter and colon from the path designation. SaveImage(Img,Buf:word; x1,y1,x2,y2:integer; Style:word):boolean Use this function to save an image to the buffer and/or disk. "Img" specifies the Img reference number, "Buf" specifies the buffer to use, "x1,y1,x2,y2" specifies the area of the screen to save, and "Style" specifies how to save the image. If the Image could not be saved, then SaveImage will return false. DisplayImage(Img,Buf:word; ImgClr:boolean):boolean Use this function to display the image. "Img" specifies the image reference number to find. "Buf" specifies the buffer to use, and ImgClr specifies whether to delete the image after it is used. If ImgClr is false, then the image will not be deleted and DisplayImage can refer to it again at a later date. If the specified image is not found, then DisplayImage will return false. FlushImage(Buf:word):boolean Flushes an image to disk from the buffer if there is an image in the buffer. You can use this before changing a buffer to insure that no images are lost. If the image could not be flushed (such as due to a disk error), the function will return false. DeleteImage(Img,Buf:word):boolean This deletes an image from the buffer and/or disk. If the specified image was not found the function will return false. <eof>